'\"macro stdmacro
.\"
.\" Copyright (c) 2014 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMLOGMV 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogmv\f1, \f3pmlogcp\f1 \- move (rename) or copy Performance Co-Pilot archive files
.SH SYNOPSIS
\f3pmlogmv\f1
[\f3\-cfNV?\f1]
[\f3\-D\f1 \f2debug\f1]
\f2srcname\f1
\f2dstname\f1
.br
\f3pmlogcp\f1
[\f3\-cfNV?\f1]
[\f3\-D\f1 \f2debug\f1]
\f2srcname\f1
\f2dstname\f1
.SH DESCRIPTION
A Performance Co-Pilot (PCP) archive consists of multiple files as
created by
.BR pmlogger (1).
.B pmlogmv
allows all the files of a single PCP archive
to be moved or renamed as a group in a single operation.
Similarly
.B pmlogcp
copies all the files of single PCP archive in a single operation.
.PP
The
.I srcname
argument identifies the target archive, and may be either the basename
that is common to all files in that archive or one of the archive's
files.
.PP
The new archive's basename is
.IR dstname ,
except when
.I dstname
is an existing directory, in which case the files are moved or copied
into
.I dstname
using the same archive basename as
.IR srcname .
.PP
Because PCP archives are important records of system activity, special
care is taken to ensure the integrity of an archive's files.
For recoverable problems encountered during the execution of
.B pmlogmv
or
.BR pmlogcp ,
all the files associated with
.I srcname
will be preserved, and no new files with the
.I dstname
prefix will be created.
``Recoverable problems'' include signals that can be caught (such as SIGHUP,
SIGINT, SIGQUIT and SIGTERM), permissions issues, new files already existing,
file system full events, etc.
.PP
The implementation of
.B pmlogmv
tries to use
hard links in the file system and so follows the semantic
restrictions of
.IR ln (2)
which for most systems means the directories containing both
the
.I srcname
and the
.I dstname
PCP archive files need to be within the
.B same
file system.
When this is not possible,
.B pmlogmv
falls back to using
.BR cp (1)
to copy
.I srcname
to
.IR dstname .
.PP
.B pmlogcp
always uses
.BR cp (1).
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-c\fR, \fB\-\-checksum\fR
Paranoid checking mode when
.BR cp (1)
is needed and each file's checksum is computed for the
original file and the copied file, and the checksums must match before
the copy is considered acceptable.
The checksum command is chosen by trying the following in turn until
one is found to be executable:
.BR md5sum (1),
.BR sha256sum (1),
.BR sha1sum(1)
and
.BR sum (1).
If no executable checksum command is found, a warning is issued and the
checksum check is skipped.
.TP 5
\fB\-f\fR, \fB\-\-force\fR
Normally
.B pmlogmv
and
.B pmlogcp
take a conservative view in respect of
.I dstname
and will not proceed if
.I dstname
contains any characters that are likely to cause a problem for
.BR sh (1).
This includes ``glob'' characters like ``?'', ``*'' and ``['', shell
syntax meta characters like ``('', ``|'', ``;'' and ``&'', shell
I/O redirection characters like ``<'' and ``>'', the dollar sign,
a space, etc.
.RS
.PP
The
.B \-f
flag forces
the rename or copy to proceed, even if
.I dstname
contains any of these ``unsafe'' characters.
.RE
.TP
\fB\-N\fR, \fB\-\-showme\fR
Perform a dry-run, checking and reporting what changes would
be made without making any changes.
.TP
\fB\-V\fR, \fB\-\-verbose\fR
Enable verbose mode.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH DIAGNOSTICS
All error and warning messages are intended to be easily understood and
errors produce a non-zero exit status.
.SH DEBUGGING OPTIONS
The
.B \-D
or
.B \-\-debug
option enables the output of additional diagnostics on
.I stderr
to help triage problems, although the information is sometimes cryptic and
primarily intended to provide guidance for developers rather end-users.
.I debug
is a comma separated list of debugging options; use
.BR pmdbg (1)
with the
.B \-l
option to obtain
a list of the available debugging options and their meaning.
.SH SEE ALSO
.BR cp (1),
.BR ln (1),
.BR md5sum (1),
.BR PCPIntro (1),
.BR pmlogger (1),
.BR sha1sum (1),
.BR sha256sum (1)
and
.BR LOGARCHIVE (5).

.\" control lines for scripts/man-spell
.\" +ok+ md {from md5sum} sha {from sha256sum}
